Skip to content

Adjust alt text generation to more closely match the W3C Alt decision tree#374

Merged
jeffpaul merged 10 commits intoWordPress:developfrom
dkotter:fix/alt-text-instructions
Apr 8, 2026
Merged

Adjust alt text generation to more closely match the W3C Alt decision tree#374
jeffpaul merged 10 commits intoWordPress:developfrom
dkotter:fix/alt-text-instructions

Conversation

@dkotter
Copy link
Copy Markdown
Collaborator

@dkotter dkotter commented Apr 6, 2026 •
edited by github-actions bot
Loading

What?

Closes #350

Adjust alt text generation to better consider the W3C Alt decision tree

Why?

Currently our alt text generation experiment generates alt text that is more or less just a description of the image. While this isn't completely incorrect, it doesn't account for other situations where the alt text should be something else, like if an image is decorative or if the image is acting as a link.

Based on the feedback in #350, this PR adjusts the experiment to try and more closely match the W3C Alt decision tree, noting it's still up to the LLM to honor those guidelines.

How?

  • Add a new image_meta param to our Alt Text Generation Ability
  • Use this new param to pass in information about the image, like if it's wrapped in a link or the caption text
  • Add support for return blank alt text and marking an image as decorative
  • Update our system instructions to be more specific in their guidance

Use of AI Tools

Used both Claude Code running Opus 4.6 and Cursor running GPT-5.3 Codex to generate separate plans and execute those plans. I then compared the approaches and combined bits and pieces of both to get to a final state

Testing Instructions

  1. Checkout this PR and run npm i && npm run build
  2. Turn on the Alt Text Generation Experiment
  3. Ensure you have a provider connected that supports vision models
  4. Create a post and insert an image somewhere into the content
  5. Generate alt text for that image and ensure it is accurate
  6. Add a link around the image and generate it again, ensuring the alt text mentions the link
  7. Generate alt text for an image in the media library, ensuring that works
Open WordPress Playground Preview

@dkotter dkotter added this to the 0.7.0 milestone Apr 6, 2026
@dkotter dkotter self-assigned this Apr 6, 2026
@github-actions
Copy link
Copy Markdown

github-actions bot commented Apr 6, 2026

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: afercia <afercia@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@codecov
Copy link
Copy Markdown

codecov bot commented Apr 6, 2026 •
edited
Loading

Codecov Report

❌ Patch coverage is 48.00000% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.77%. Comparing base (0b343a4) to head (9bcac1e).
⚠️ Report is 52 commits behind head on develop.

Files with missing lines Patch % Lines
includes/Abilities/Image/Alt_Text_Generation.php 45.83% 13 Missing ⚠️
Additional details and impacted files 
@@              Coverage Diff              @@
##             develop     #374      +/-   ##
=============================================
+ Coverage      59.75%   59.77%   +0.01%     
- Complexity       701      702       +1     
=============================================
  Files             49       49              
  Lines           3558     3572      +14     
=============================================
+ Hits            2126     2135       +9     
- Misses          1432     1437       +5
Flag Coverage Δ
unit 59.77% <48.00%> (+0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@dkotter dkotter mentioned this pull request Apr 6, 2026
Closed
6 tasks
@jeffpaul jeffpaul self-requested a review April 7, 2026 13:38
jeffpaul
jeffpaul approved these changes Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@jeffpaul jeffpaul left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Works well in testing, but let's hold on merging this until we determine how best to handle #340 as a potential blocker in the 0.7.0 release.

@dkotter dkotter mentioned this pull request Apr 7, 2026
Merged
@jeffpaul jeffpaul merged commit afc7cb4 into WordPress:develop Apr 8, 2026
17 of 18 checks passed
@dkotter dkotter deleted the fix/alt-text-instructions branch April 8, 2026 21:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jeffpaul jeffpaul jeffpaul approved these changes

Assignees

@dkotter dkotter

Labels

None yet

Projects

None yet

Milestone

0.7.0

Development

Successfully merging this pull request may close these issues.

Alt text generation must describe the purpose and function of the image rather than the image content.

2 participants

@dkotter @jeffpaul